CD ROM Paradise Collection 4/CD ROM Paradise Collection 4 1995 Nov.iso/graphics/gip_02.zip/GIP-SYSP.DOC

Text File | 1994-12-18 | 21KB | 523 lines

Graphic Interchange Protocol (GIP) Technical Standards -- Request For Comment
Document #1 release .02

New stuff since .01 has a "│" as the first character of the line.

Using GIP with GIP compatible BBS's--the sysop's viewpoint.


OVERVIEW

  Advantages of GIP

    Open architecture for future expandability.
    Single-pass optimized communications.
    Public domain source code.
    Automatic updating protocol for graphic files.
    GIP codes work just like ANSI codes.
    Object definition ability.

  Disadvantages of GIP

    Reliance on a public, changing, standard.

  Comparison with other methods

    The fastest general-BBS protocol.
    Requires no licensing fees.
    Requires little code development.
    Uses current utilities for graphic creations.
    Easy to implement, design, and alter graphics on the BBS.
    Support for SVGA modes.


HOW IT WORKS

  GIP commands, like ANSI commands, are meant to be imbeded in text.  At the
  lowest capability of the commands (drawing) you need nothing more than a
  text editor.

  You cannot use ANSI codes along with GIP codes.

  The GIP code is ASCII 19, or "" (the double-exclaimation points).

  Like ANSI codes, you can put these codes into strings of text in the
  program itself.  And can use an editor to create them (well, at least
  PC-Write does let you).

  It's a simple system:
    <><Do what ID letter><What to do stuff><;>

  The user does need to have a GIP compatible communications program to
  view your creations.

  The software handles everything about the exchange.  You need not worry
  about how it does what it does, how users store/update the data, or whether
  they can do the commands or handle the level of graphics.  You need only
  design what you want users to see.

  You do not need to make an archive of your graphics available for users
  to download.

  Any "hot" keys (such as menu command keys) are not valid as the graphics
  are being displayed.  This is done so both sides stay in sync about the
  graphics/text being displayed.


COMMANDS

  h and v are coordinates.  These go from 0 to N - 1 (N depends on the
  graphics mode).  0,0 is the upper-left corner of the screen.  The
  numbers are integers (0, 1, 2, 3, etc.)   "h" are the cordinates along
  the line (horizontal coordinates), and "v" are the vertical (up/down)
  coordinates.

  d is the depth for 3-D, and isn't coded for yet.

  The h,v,d values may either represent actual screen coordinates, or
  offsets from the last-used coordinate, command dependent.  When they are
  offset values, negative numbers can be used.  A "0" offset value means to
  draw at least one pixel--since you are drawing from the current pixel to
  pixel location + 0.

  n is a number, and its values are also command dependent.


  COMMAND   DESCRIPTION


  Sn;       Switch to graphics mode n.

            Where n is:  0 for standard 80x25 mode.
                         1 for 320x200x4 CGA (testing mode only).
                         2 for 640x480x16 VGA.
                         3 for 320x200x256 VGA.
                         4 for 640x480x256 SVGA.
                         5 for 800x600x256 SVGA.

            Example:  S2;
                      Begins graphic mode 2.
                      S0;
                      Returns back to normal (ANSI) mode.

            Modes 4 and 5 require an SVGA card, and are a bit less-automatic
            for beginner users.  For general-audience graphics, you should
            stick with modes 2 and 3.

            Mode 2 provides for 80x60x16 text.  While Mode 4 only provides
            for 40x25x256 text.

            For normal operations, mode 2 is the only real practical mode.
            It's drawback is that some sysops might find it's text a little
            small.  This will be solved for in the future when I add support
            for more fonts.

│           This acts as CLS: it clears the screen, and resets the h,v,d
│           current coordinates to 0,0,0.  It also sets the color to 15,
│           which is bright white in 640x480x16 mode.  Finally, the line
│           pattern is also reset to that of a solid line.

│           An Sn; code will always start a GIP session.  That is, you
│           cannot do "Cn;Sn;" and expect the software to act on the
│           Cn;, since it's before we went into GIP mode, and will be
│           ignored.


  Cn;       Switch to color n.

            Where n is:  0 to 15
                         0 to 255

            Example:  C0;
                      Change the current color to black.

            This depends on what mode you are in (either 16 or 256 colors).
            The 16 color mode follows the same color scheme as ANSI does.


  Gh,v,d;   Go to point h,v,d.

            Example:  G10,10,0;
                      will move to graphics location 10,10.

            Nothing is displayed.

            h,v,d cannot be negative numbers.

            This is the most used command, as it's used to place lines,
            boxes, and text.


  Mh,v,d;   Go to offset point h,v,d.

            Example:  G20,20,0;
                      will move from the current location to offset 20,20.
                      After the call, the new current location is 10,10 +
                      the h,v offset (30,30).

            Nothing is displayed.

            This command is usually only used when defining objects, which
            by their nature can't be screen coordinate dependant.


  Lh,v,d;   Draw a line from current point to h,v,d.

            Example:  L20,20,0;
                      will draw a line, in the current color, from the
                      current location to offset 20,20.  After the call,
                      the new current location is 10,10 + the h,v offset.

            There is no "draw a point" command.  To draw points, use very
            short lines.


  Bh,v,d;   Draw a rectangle from the current postition to h,v,d.  Where
            h,v,d is the opposite corner of the rectangle.

            Example:  B20,20,0;
                      will draw a line-box, in the current color, from the
                      current location to offset 20,20.  After the call,
│                     the current location is still 20,20,0.


  Fh,v,d;   Draw a filled/solid rectangle from the current postition to
            corner h,v,d.  Where h,v,d is the opposite corner of the rectangle.

            Example:  F20,20,0;
                      will draw a filled box, in the current color, from the
                      current location to offset 20,20.  After the call,
│                     the current location is still 20,20,0.

            The current pattern is also used.

            If you're trying to draw a box over text, and you get "ghosting"
            of the previous stuff in that area--that's a sure sign that you
            forgot to reset your pattern to solid--that "ghosting" is pixels
            being skipped due to the pattern.

│           Using a "skip pattern" like "01010101010101010101" will double
│           the speed of the filled box display, with no noticable loss of
│           color.  This technique is excellent for doing background patterns
│           onto a black screen--since there is no reason for a background
│           pattern to be solid rather than 50/50--they look nearly the same.
│           But this trick cannot be used when writing over other colors, nor
│           when the text you wish to put over this pattern is a dark black,
│           blue, grey--as the extra black pixels will make it look fuzzy.


  fPATHNAME;
            The file exchange protocol.  The heart of GIP.  It is used to
            send any files.  Including .GIF's, .ICO's, .MOD's, .VOC's, etc.
            The software determines what to do with your file based on the
            file's extension.  So if it's a GIF, use .GIF display, etc.

            Example:  fC:\BBS\NCD.ICO;
                      would display C:\BBS\NCD.ICO with it's upper-left
                      corner starting at the current location.
                      fC:\BBS\METAL.VOC;
                      would play C:\BBS\METAL.VOC.

            It's really an "update protocol"--since the file will not be
            sent if the current version of the file already exists on the
            callers disk in his "your BBS identifier" directory.

            The path is not sent, only the filename.

            We stay at the current coordinates--they are not changed.

            For now, only .ICO icon files are handled.  These are "standard"
            766 byte sized 16-color icons.

            .BMP files also sort-of work.  Not in CGA mode, and the dark
            colors are off with some BMP's.  Doesn't decode RLE compressed
            BMPs either.

            Any other file you send will be sent, but will be assumed to be
            a standard text or ANSI file and displayed as such.

            The exception is .BMP's.  However, the current code I have to
            display .BMP's displays them with the wrong colors.  I only
            tell you now because sometimes it displays them properly (such
            as most of the 16 color BMP colors).


  Pn,s;     Set the "pattern" to use for drawing lines and filling boxes.

            Where n is:  0 to 65534
                         -1 to 32767
                         A 16 character pattern of 0's and 1's (example:
                         0000111100001111).

            Where s is:  -15 to 15

            Example:  P1,0;
                      or
                      P0000000000000001,0;
                      will use "               ∙" (15 blanks and then a
                      dot) for the pattern for drawing lines, boxes, etc.

            The pattern is the same as formed by the ON/OFF bits of the
            number n, with an ON bit being a visible pixel, and an OFF
            bit being a skipped pixel.

            An exception is zero, this is changed to "-1" or "65534" and is
            equivalent to a solid line of pixels.  I did this to make it
            easier to work with, and because "all pixels off" lines aren't
            likely to be needed.

            The default is a solid line, and this default is selected each
            time you change the screen mode.  Otherwise the pattern defined
            stays in effect until you do a new pattern-change or another
            screen mode change.

            At the start of each line drawing order, we begin with the left-
            most pixel, and continue on through to the right.  Starting again
            at the left after the 16th pixel.

            The exception to this is filled boxes.  In order to avoid
            streaking lines, we incorpate "s"--the shift value.  After each
            line when drawing a filled box, the bit pattern will be shifted
            according to s.  A negative value means to rotate left, a
            positive value means to rotate right, a zero means no shifting.

            For example, for the "on-off-on-off" pattern, no shifting would
            yield not a pattern, but an organized set of vertical lines.  If
            you shift more than one, you get organized slanted lines.  So the
            shift you use depends on that pattern you use, and will probably
            require a little trial and error.


  On;~xxx~  Define an object for later display.

            Where n is:  0 to 255

            Example:  O1;~C3;G5,5,0;L15,5,0;L15,15,0;L5,15,0;L5,5,0;~
                      Which defines Object #1 to be orders to: change to
                      color 3 and goto 5,5 and draw a box.

            It's very flexible, you can have GIP codes and normal text
            intermixed.

            It's not displayed at the time you define/send it.

            Only three restrictions:  no GIP "f<pathname>" commands nor other
            object commands (either defining or using) should be inside the
            two "~" characters.  And, of course, no "~" allowed inside the
            definition.

            This is the cyberspace command, with which we will have
            cyberspace in the future.

            When defining objects, the maximum size of any one object is
            2048 bytes, and the size of all objects must not exceed 8192
            bytes.  If you need to exceed these limits, I recommend using
            either an icon or graphic image file.


  on;       Call up and display/use an Object.

            Where n is:  0 to 255

            Example:  o1;
                      Will display Object #1 we defined earlier.

            This offers fast graphics, since the commands do not have to
            be re-sent each time you want to display the same thing.
            It also offers the sysop convience.  When testing postioning
            of GIP drawings, and when working with lots of the same
            drawings.

ASCII TEXT

  Text is like lines--its pixels are drawn on top of whatever is there
  already.  It uses whatever was the last defined color, at whatever was
  the last location.

  For now, only an 8x8 font is used.  After each character is displayed,
  we automatically add 8 to the orginal (pre-drawing) horizontal location,
  which has the effect of putting us right where the next character would
  be drawn.

  For spans of spaces, 8 or fewer spaces is more efficient than using a
  "Gh,v,d;" command to move you ahead.

  For CR/LF's, we simply change the horizontal coordinate to zero, and add
  8 to the vertical coordinate.  This allows us to display normal text going
  down the screen normally.  However, there are problems when you reach the
  end of the screen--as the there no scrolling in GIP (nor any wraparound to
  the next lines).  Think of CR/LF's this way: just another cursor positioning
  command: "go to start of next line".

  Usually the effects of CR/LF's do not matter.  They are very useful for
  making GIP files readable.  So don't be afraid to use them for that purpose.

  The full 256 character ASCII set may be sent and displayed except for the
  following codes: 10, 13, 19, 12, 22, 25, 27
  These codes are used by ANSI, GIP, Avatar, and text to signify something
  besides their normal ASCII character.


EXAMPLES

  "S2;fC:\BBS\NODE001\GRA\PIC1.ICO;G300,300,0;Hi there!"

  will: clear the screen and go to graphics mode (S2;)
        send the file PIC1.ICO (if the caller doesn't have it already)
          (fC:\BBS\NODE001\GRA\PIC1.ICO;)
        locate pixel 300,300 (G300,300,0;)
        and display "Hi there!" at that point.

  "S2;G300,300,0;fC:\BBS\NODE001\GRA\PIC1.ICO;Hi there!"

  will: same as the above, but draws the icon at 300,300 and "Hi there!"
        right after the icon.


NOTES

  GIP codes, like ANSI, can be put into files and displayed.  I recommend
  the extension .GIP (like .ANS) but it's not required.

  GIP contains no error-checking stuff, and so should only be used by MNP
  modems (the baud doesn't matter).


│PROBLEMS
│
│  If for some reason things just are not being positioned where you expect,
│  and no matter what you do does not seem to change it.  Chances are the
│  problem is due to you forgetting about CR/LF's.
│
│  At the end of each line, that CR/LF is noticed, and causes the Vertical
│  position to get +8, and the Horizontal position to become 0.  CR/LF's
│  are great for cleaning up a .GIP file, and very useful with text, but
│  when working with mostly graphics, do not forget that it does alter the
│  coordinates.
│
│  Forgetting to turn off a pattern when drawing text causes the text to
│  look sloppy.
│
│  Another tricky problem when laying down a filled area of one pattern,
│  and then putting another pattern (that isn't solid) on top of that.  If
│  you were expecting the second pattern, you might be surprised to get
│  something unexpected.  Because a few of those pixels from the first
│  pattern will pass on through--enough to make a nice on/off pattern into
│  a unwanted moire pattern.
│
│  Other common problems include forgetting the double-quotation in front
│  of a GIP command, or the semi-colon at the end of the command, or using
│  semi-colons instead of commas inside the GIP command.
│
│  When using dithered backgrounds (like on/off patterns) one thing you
│  need to watch/play with is text colors that you put onto these areas.
│  Because of the dithering, the dark spots, or light spots, can make the
│  text look real fuzzy.


CONVERTING TEXT FILES TO GIP

  For bare bones conversion of a standard text file to gip, there are only
  two things to do:

    Add a "Sn;Cn;" at the start of the file.
    Add a "S0;" at the end of the file.


CONVERTING ANSI FILES TO GIP

  These are the steps to follow that to make conversi of ANSI's easier:

  First, convert the "[xC" "cursor jumping" commands to their spaces
  equivalent.  Example "[7C" becomes "       ".  You can optimize it with
  "Gh,v,d;" commands later.  A "Gh,v,d;" command uses 8 characters in it's
  transmission, so there is nothing to be gained by reducing gaps 8 or fewer
  characters to "Gh,v,d;" calls.

  Second, convert the "[x,y,zm" color commands.  Easy except for background
  commands "[44m"--in which case you'll probably want to first draw a filled
  box of the length desired and then draw the characters on top of it.

  The above stuff on converting normal text files is useful too.

  0,8,16,24 etc. correspond to normal 80x25 text columns.


VIEWGIP

  Also enclosed is VIEWGIP.EXE.

  ViewGIP will let you display files with GIP codes inside them.  It works
  much like TYPE filename.ANS works.  Just type: VIEWGIP filename.GIP

  The only limitations are that the two SVGA modes won't work with this
  viewer, and the maximum file size is 16k.

  The program will display the file, and then wait for you to hit a key.
  For best viewing, I recommend you remove any "S0;" mode-to-normal you
  have at the end of the file before displaying.

  While it is waiting for you to hit a key.  If you hit one of the
  directional keys (arrows) this will show the coordinates of the point
  at which the display end.  You can then continue to use the directional
  keys to move about--identifying other locations.  This is very useful
  when building menus/etc.  Hit any non-directional key to end.


COMMIE

  Commie is available in a separate archive.  Your users can use this
  program to see your GIP graphics.


CONCLUSION

  All of the above stuff is already coded and done.  The only supported file
│ display format right now is ".ICO" for icons, and .BMP for images--and I'm
│ looking for source code to display ANY other graphic or sound formats.

  The stuff below still needs to be done, and will be available sometime in
  the future:

    d coordinates (depth/3-D stuff)
    GIFs/TIFs/PCXs/BMPs
    sound files (VOC/MOD)
    fonts (TrueType preferred)
    circle's/elipses
    etc.

  This is a very open-ended standard.  It's success and power depend on other
  people supplying code for many of the things not done.  For instance, I
  don't know 3-D graphics programming, the drivers for sound cards, or how to
  display the various image file formats.  I'll teach myself and get it, but
  reinventing wheels is not efficient.  So feel free to help.



I can be reached for comment/suggestions at:

    Immortality
    414-643-1576
    24 hrs.

Either log in, or just dump your NetMail on me.

John Rohner
December 1994



I hereby release the GIP specifications, and any code specific only to
implementing the GIP specifications I include as an example, to the Public
Domain for full, free, and uncredited distribution by other GIP-capable
program authors.

With the premediated hope that authors will simply import the code into their
program to provide GIP support.  With a promise to never challenge nor
discredit said authors, and that this Public Domain declaration shall be
eternal.

This declaration does not extend to the various subroutines used to form the
example programs in which the GIP subroutines reside.